Описание агента
Инструкции по настройке TI Feeds Agent
- Агент Solar TI Feeds представляет собой программное обеспечение для интеграции с облаком TI Feeds, предназначенное для автоматизации получения различных фидов и их доставки конечному потребителю в различных форматах
- Решение представлено в виде Docker-образа, что обеспечивает простоту развертывания и масштабируемость
- Агент самостоятельно выполняет запросы к серверу, аутентифицируется и выгружает необходимые данные
Функциональные особенности агента
- Возможность настройки работы агента при помощи конфигурационного файла
- Встроенный планировщик, позволяющий настраивать расписание загрузки фидов
- Трансформация и фильтрация полученных данных
- Поддержка различных форматов вывода данных (CSV, TXT, Kafka)
- Возможность интеграций с СЗИ
- Возможность настройки способа получения данных:
- Полная выгрузка всех данных при каждой загрузке
- Загрузка только изменений с предыдущего обновления для экономии ресурсов и оперативного получения новых фидов
Подготовка к установке
Перед началом установки убедитесь, что выполнены следующие требования:
1. Программное обеспечение
- Операционная система: Unix-подобная ОС (Linux или macOS)
- Контейнеризация:
- Docker версии 22 или выше
- Docker Compose версии 2
- Архив с агентом: В случае ручной установки скачайте установочный пакет
2. Аппаратные требования (при развертывании на виртуальной машине)
Если вы планируете развернуть агент на виртуальной машине, обеспечьте следующие минимальные характеристики:
- Процессор: 2-4 vCPU
- Оперативная память: 8 ГБ vRAM
- Диск: 50 ГБ HDD
Скачивание и распаковка архива
- Откройте терминал и перейдите в директорию, куда будете устанавливать агент
- Создайте директорию для агента, выполнив команду:
mkdir -p agent - Скачайте и распакуйте в эту директорию последнюю версию агента
curl -fkSL "https://cdn.data.rt-solar.ru/agent/latest.tar.gz" | tar -xzf - -C agent - Перейдите в распакованную директорию:
cd agent
Альтернативный способ установки через Docker Registry
Вместо скачивания и распаковки полного архива вы можете использовать готовый образ из Docker Registry и отдельный файл docker-compose.yml. Этот способ удобен, когда требуется только настроить оркестрацию и конфигурацию, не храня архив целиком.
Шаги:
- Скачайте файл
docker-compose.yml
Cкопируйте содержимое файла и сохраните какdocker-compose.ymlв рабочей директории.
Содержимое файла docker-compose.yml:
services:
agent:
image: registry.data.rt-solar.ru/4rays/tic/agent:v3.0.22-public
ports:
- "8080:8080"
- "8090:8090"
volumes:
- ./pkl/configs/base_pipeline.pkl:/configs/config.pkl:ro
- ./workdir:/workdir
- ./certs:/workdir/certs
environment:
### Logger settings
# Log level: debug, info (default), warn, error
# - TIC_AGENT_LOG_LEVEL=
# Log file name, default agent.log
# - TIC_AGENT_LOG_FILE_NAME=
# Log file max size in mb, default 100
# - TIC_AGENT_LOG_FILE_MAX_SIZE_MB=
# Log file max backups, default 1
# - TIC_AGENT_LOG_FILE_MAX_BACKUPS=
# Log file max age in days, default 7
# - TIC_AGENT_LOG_FILE_MAX_AGE_DAYS=
### TI Cloud API settings
# API endpoint URL
- TIC_AGENT_API_URL=https://api.data.rt-solar.ru
# JWT token (can be provided without "Bearer" prefix)
# - TIC_AGENT_API_TOKEN=
# API pool interval, in seconds, default 600
# - TIC_AGENT_API_POOL_INTERVAL=
# API iocs batch size, from 1 to 1000, default 1000
# - TIC_AGENT_API_BATCH_SIZE=
# DB pool interval, in seconds, default 60
# - TIC_AGENT_DB_POOL_INTERVAL=
# DB iocs batch size, from 1 to 1000, default 100
# - TIC_AGENT_DB_BATCH_SIZE=
# Proxy connection string (e.g., socks5://user:password@proxy.domain:port)
# - TIC_AGENT_PROXY=
### Kafka settings
# Comma-separated list of broker addresses (e.g., localhost:9092)
# - TIC_AGENT_KAFKA_BROKERS=
# List of target topics to produce messages to
# - TIC_AGENT_KAFKA_TOPICS=
# SASL auth mechanism (e.g., PLAIN, SCRAM-SHA-256, SCRAM-SHA-512)
# - TIC_AGENT_KAFKA_SASL_MECHANISM=
# - TIC_AGENT_KAFKA_SASL_PASSWORD=
# - TIC_AGENT_KAFKA_SASL_USERNAME=
### CyberTrace settings
# API endpoint URL (e.g., https://ct.domain)
# - TIC_AGENT_CYBERTRACE_ADDRESS=
# Credentials for Basic Authentication
# - TIC_AGENT_CYBERTRACE_PASSWORD=
# - TIC_AGENT_CYBERTRACE_USER=
# Authentication API token
# - TIC_AGENT_CYBERTRACE_TOKEN=
# Proxy connection string (e.g., socks5://user:password@proxy.domain:port)
# - TIC_AGENT_CYBERTRACE_PROXY=
### MISP settings
# API endpoint URL (e.g., https://misp.domain)
# - TIC_AGENT_MISP_ADDRESS=
# Credentials for Basic Authentication
# - TIC_AGENT_MISP_PASSWORD=
# - TIC_AGENT_MISP_USER=
# Authentication API token
# - TIC_AGENT_MISP_TOKEN=
# Proxy connection string (e.g., socks5://user:password@proxy.domain:port)
# - TIC_AGENT_MISP_PROXY=
### NAD settings
# API endpoint URL (e.g., https://nad.domain)
# - TIC_AGENT_NAD_ADDRESS=
# Credentials for Basic Authentication
# - TIC_AGENT_NAD_PASSWORD=
# - TIC_AGENT_NAD_USER=
# Authentication API token
# - TIC_AGENT_NAD_TOKEN=
# Proxy connection string (e.g., socks5://user:password@proxy.domain:port)
# - TIC_AGENT_NAD_PROXY=
### OpenCTI settings
# API endpoint URL (e.g., https://opencti.domain)
# - TIC_AGENT_OPENCTI_ADDRESS=
# Authentication API token
# - TIC_AGENT_OPENCTI_TOKEN=
# Traffic Light Protocol level: red (default), amber, green, white
# - TIC_AGENT_OPENCTI_TLP=
# STIX object type: indicator (default), observable
# - TIC_AGENT_OPENCTI_TYPE=
# API version: 6, 7 (default)
# - TIC_AGENT_OPENCTI_API_VERSION=
# Proxy connection string (e.g., socks5://user:password@proxy.domain:port)
# - TIC_AGENT_OPENCTI_PROXY=
### R-Vision settings
# API endpoint URL (e.g., https://rvision.domain)
# - TIC_AGENT_RVISION_ADDRESS=
# Authentication token (sent via 'x-api-key' header)
# - TIC_AGENT_RVISION_TOKEN=
# Integration identifier (sent via 'x-api-integration-id' header)
# - TIC_AGENT_RVISION_INTEGRATION_ID=
# Proxy connection string (e.g., socks5://user:password@proxy.domain:port)
# - TIC_AGENT_RVISION_PROXY=
-
Получите конфигурационные файлы (pkl)
Конфигурации pipeline и шаблоны находятся в директорияхpkl/configs/иpkl/internal/установочного архива. Извлеките их из скачанного ранееlatest.tar.gzили скачайте отдельно в разделе Интеграции. Скопируйте необходимые файлы в структуру каталогов, соответствующую монтированию вdocker-compose.yml(например,./pkl/configs/base_pipeline.pkl). -
Настройте переменные окружения
Отредактируйте файлdocker-compose.yml, указав как минимум:TIC_AGENT_API_TOKEN– ваш JWT-токен для доступа к Solar TI Feeds.- При необходимости другие переменные (логирование, прокси, настройки интеграций и т.д.).
-
Запустите агент
Выполните в директории сdocker-compose.yml:
docker compose up -d
При первом запуске Docker автоматически загрузит образ из регистри registry.data.rt-solar.ru/4rays/tic/agent:v3.0.22-public.
Если вы хотите загрузить образ вручную (например, для проверки), используйте команду:
docker pull registry.data.rt-solar.ru/4rays/tic/agent:v3.0.22-public
Она необязательна, так как docker compose up сам выполнит загрузку при необходимости.
Дальнейшая настройка и управление агентом ничем не отличаются от описанных в остальных разделах документации.
Описание установочных файлов
Установочный комплект включает в себя Docker-образ контейнера и конфигурационные файлы, с помощью которых можно настраивать агента без внесения изменений в программный код:
| Файл | Назначение |
|---|---|
4rays_tic_agent.tar | Docker-образ агента Solar TI Feeds |
docker-compose.yml | Готовый файл оркестрации для запуска контейнера с предопределёнными переменными окружения и монтированием томов |
ReadMe.txt | Краткая инструкция по быстрому запуску и базовой настройке агента |
pkl/internal/agent.pkl | Базовая конфигурация агента описывающая все доступные структуру, типы данных, компоненты (генераторы, трансформеры, sink'и) и возможные значения параметров |
pkl/internal/templates.pkl | Шаблоны конфигурации содержащие предопределённые настройки серверов, расписаний, логирования и метрик для переиспользования в pipeline |
pkl/configs/{PIPELINE_NAME}.pkl | Файлы конфигурации pipeline, определяющие логику обработки данных и параметры запуска агента. Имя файла соответствует названию СЗИ, с которой выполняется интеграция (например, cybertrace_pipeline.pkl) |
Загрузка Docker-образа
Для загрузки Docker-образа выполните следующую команду:
docker load -i "4rays_tic_agent.tar"
Загрузка Docker-образа
При использовании установочного архива загрузите образ из файла:
docker load -i "4rays_tic_agent.tar"
При использовании альтернативного способа через Docker Registry этот шаг не требуется – образ будет загружен автоматически при запуске контейнера (см. раздел «Альтернативный способ установки через Docker Registry»).
Проверка загрузки
Чтобы убедиться, что Docker-образ успешно запустился выполните команду:
docker image list
В выводе должен присутствовать контейнер 4rays/tic/agent (если загружали из архива) или registry.data.rt-solar.ru/4rays/tic/agent (если использовали Docker Registry) с актуальной версией. Если в консоли появилась информация о контейнере соответствующей версии, значит образ успешно загружен.
Конфигурация агента
1. Подготовка конфигурационного файла
- Перейдите в директорию pkl/configs
- Выберите существующий файл конфигурации (например,
base_pipeline.pkl) или создайте новый - Убедитесь, что указаны корректные параметры для запуска:
- JWT-токен для доступа к Solar TI Feeds API
- Адрес и учётные данные интегрируемой СЗИ (например, Cybertrace)
2. Настройка Docker Compose
По умолчанию docker-compose.yml использует конфигурацию pkl/configs/base_pipeline.pkl
Данный файл монтируется как volume в контейнер по пути /configs/config.pkl
Если вы используете другой конфигурационный файл (не base_pipeline.pkl), отредактируйте в docker-compose.yml путь к файлу в секции volumes
3. Модификация логики работы (pipeline)
Если требуется изменить дополнительные параметры или логику обработки данных, отредактируйте pipeline в выбранном файле конфигурации {PIPELINE_NAME}.pkl
4. Переопределение переменных окружения
Базовые параметры для готовых конфигураций задаются в блоке environment файла docker-compose.yml
Переменные окружения
Основные
Для подключения к Solar TI Feeds необходимо использовать данные переменные:
| Переменная | Назначение |
|---|---|
TIC_AGENT_API_URL | Адрес сервера Solar TI Feeds (по умолчанию https://api.data.rt-solar.ru) |
TIC_AGENT_API_TOKEN | JWT-токен для аутентификации на сервере Solar TI Feeds |
Прокси-сервер (при необходимости)
При развертывании контейнера вы можете передать следующие standard-переменные:
| Переменная | Назначение |
|---|---|
TIC_AGENT_PROXY | Строка подключения к прокси (например, socks5://user:password@proxy.domain:port) |
HTTP_PROXY | URL прокси-сервера для HTTP-запросов (например, http://corp.local) |
HTTPS_PROXY | URL прокси-сервера для безопасных HTTPS-запросов |
NO_PROXY | Список исключений (хостов, доменов или сетей), запросы к которым должны идти напрямую, минуя прокси |
Настройки логирования
| Переменная | Назначение | По умолчанию |
|---|---|---|
TIC_AGENT_LOG_LEVEL | Уровень логирования: debug, info, warn, error | info |
TIC_AGENT_LOG_FILE_NAME | Имя файла лога | agent.log |
TIC_AGENT_LOG_FILE_MAX_SIZE_MB | Максимальный размер файла лога в МБ | 100 |
TIC_AGENT_LOG_FILE_MAX_BACKUPS | Максимальное количество резервных копий логов | 1 |
TIC_AGENT_LOG_FILE_MAX_AGE_DAYS | Максимальный срок хранения логов в днях | 7 |
Настройки API
| Переменная | Назначение | По умолчанию |
|---|---|---|
TIC_AGENT_API_POOL_INTERVAL | Интервал опроса API Solar TI Feeds (в секундах) | 600 |
TIC_AGENT_API_BATCH_SIZE | Размер пакета индикаторов при загрузке из API (от 1 до 1000) | 1000 |
Настройка обработки данных из локальной базы
Эти параметры управляют чтением индикаторов из промежуточной SQLite-базы и повторной обработкой ошибочных записей.
| Переменная | Назначение | Значение по умолчанию |
|---|---|---|
TIC_AGENT_DB_POOL_INTERVAL | Интервал чтения из БД (в секундах) | 600 |
TIC_AGENT_DB_START_DELAY | Задержка перед первым циклом чтения (в секундах) | 60 |
TIC_AGENT_DB_BATCH_SIZE | Количество записей, извлекаемых за один запрос | 100 |
TIC_AGENT_DB_BATCH_DELAY | Задержка между пакетами чтения (в миллисекундах) | 100 |
Настройки Kafka
| Переменная | Назначение |
|---|---|
TIC_AGENT_KAFKA_BROKERS | Список адресов брокеров Kafka через запятую (например, localhost:9092) |
TIC_AGENT_KAFKA_TOPICS | Список топиков для отправки сообщений |
TIC_AGENT_KAFKA_SASL_MECHANISM | Механизм SASL-аутентификации (PLAIN, SCRAM-SHA-256, SCRAM-SHA-512) |
TIC_AGENT_KAFKA_SASL_USERNAME | Имя пользователя для SASL |
TIC_AGENT_KAFKA_SASL_PASSWORD | Пароль для SASL |
Запуск и проверка функционирования
Для запуска агента необходимо перейти в директорию, в которой был распакован установочный комплект, и ввести в консоли команду для запуска агента:
docker compose up
Для запуска агента в фоновом режиме (как службы) необходимо ввести команду:
docker compose up -d
После запуска контейнера в обычном режиме в консоль будет выводиться служебная информация о работе агента. При запуске в режиме службы для просмотра аналогичной информации необходимо воспользоваться командой:
docker logs {CONTAINER_NAME}
или просмотреть .log файлы, находящиеся в директории ./workdir/logs, если в конфигурационном файле задана запись в лог-файл.
Чтобы посмотреть результаты работы агента, перейдите в поддиректорию ./workdir, находящуюся в директории, из которой был запущен агент. Там размещаются файлы, содержащие результаты работы агента. Если в конфигурационном файле установлены соответствующие значения, то в этой же директории могут быть созданы файл с логами работы агента и файл базы данных SQLite, хранящий в себе состояние работы агента.
Для остановки агента нажмите сочетание клавиш Ctrl+C.
Перезапуск агента
В процессе эксплуатации может возникнуть необходимость в полном перезапуске агента с очисткой его текущего состояния. Это может потребоваться для устранения сбоев в работе, очистки кеша или при изменении конфигурации, требующем обработки всех данных заново.
Процедура полного перезапуска включает в себя остановку агента, удаление файла с его состоянием и последующий запуск.
Удаление файла состояния приведет к тому, что агент при следующем запуске начнет обработку данных с начала, что приведет к повторной загрузке уже полученных ранее данных.
Шаги для полного перезапуска агента:
1. Остановите работающий агент:
- Если агент запущен в интерактивном режиме (через
docker compose up), нажмите сочетание клавиш Ctrl+C - Если агент запущен в режиме службы (через
docker compose up -d), выполните в директории с агентом команду:
$ docker compose down
2. Удалите рабочую директорию агента
Для полного удаления ./workdir выполните команду:
$ rm -rf ./workdir
Команда rm -rf безвозвратно удаляет все файлы и поддиректории. Убедитесь, что путь указан верно и директория не содержит важных данных, которые не подлежат удалению.
3. Запустите агент заново, выполнив команду запуска в нужном режиме
- В интерактивном режиме:
$ docker compose up
- В режиме службы:
$ docker compose up -d
После выполнения этих шагов агент будет запущен с чистым состоянием и начнет процесс выгрузки данных сначала.
Результаты работы агента
Результаты работы агента сохраняются в директории ./workdir (относительно места запуска агента).
Структура директории:
| Путь | Содержимое |
|---|---|
| ./workdir/logs/ | Лог-файлы работы агента (например, agent.log) |
| ./workdir/artifacts/ | Выходные файлы с результатами обработки (CSV, TXT и др.) |
| ./workdir/db/db.sqlite | Файл базы данных SQLite, содержащий кэш и текущее состояние работы агента |
Примечание:
Точные пути могут отличаться в зависимости от настроек в конфигурационных файлах (templates.pkl,base_pipeline.pkl)
Сохранение результатов в формате CSV
Данные могут быть загружены в формате CSV с расширенными возможностями настройки:
- Настройка разделителей (сепараторов) между полями (запятая, точка с запятой, табуляция и др.)
- Настройка символов экранирования для специальных символов и текстовых данных
- Настройка заголовков столбцов (возможность переименования, добавления или удаления)
- Гибкая настройка содержания столбцов с выбором необходимых полей данных
Рисунок 1 – Пример CSV-файла
Рисунок 2 – Пример CSV-файла с настроенными столбцами
Также при сохранении результатов в файл можно выбрать режим записи:
- Перезапись старого файла
- Запись в конец существующего файла
- Запись в новый файл с временной меткой
Рисунок 3 – Примеры файлов в различных режимах записи
Сохранение результатов в виде списка в TXT-файле
Агент позволяет настроить получение данных таким образом, что будет выгружаться только значение индикатора без дополнительной информации для удобного формирование списков (Рисунок 4).
Рисунок 4 – Примеры TXT-файлов, содержащие только значения индикатора
Запись результатов в Kafka
Агент предоставляет возможность записи фидов отдельными сообщениями в Apache Kafka с возможностью выбрать топик, ключ и настроить формат сообщения.
Рисунок 5 – Пример записи фида в виде сообщения в формате Apache Kafka
Контакты технических специалистов
При возникновении вопросов по развёртыванию, настройке или эксплуатации ПО вы можете обратиться к специалистам службы сопровождения Solar TI Feeds по электронной почте:
support.tic@rt-solar.ru